QuickTime 3 Reference

Previous | Chapter Top | Chapter Contents

Functions

This section describes functions that can be implemented by sequence grabber channel components.

SGAddExtendedFrameReference

pascal ComponentResult SGAddExtendedFrameReference(SeqGrabComponent s,
                     SeqGrabExtendedFrameInfoPtr frameInfo);
s
Identifies a component instance that identifies the sequence grabber component connected to your channel component. The sequence grabber component provides this value when SGInitChannel is called.
frameInfo
Contains a pointer to a frame information structure defined by the SeqGrabExtendedFrameInfo data type. Your component must place the appropriate information into the record identified by this parameter. The format and content of the frame information structure are described on page 8 .

DISCUSSION

SGAddExtendedFrameReference differs from SGAddFrameReference in one respect: it uses SeqGrabExtendedFrameInfoPtr instead of a pointer to a SeqGrabFrameInfo structure.

SGAddExtendedMovieData

The SGAddExtendedMovieData function allows your channel component to add data to a movie without writing data to a movie file.

pascal ComponentResult SGAddExtendedMovieData(SeqGrabComponent s, SGChannel c, Ptr p,
                     long len, wide *offset, long chRefCon, TimeValue time, short writeType, SGOutput
                     *whichOutput);
s
Identifies a component instance that identifies the sequence grabber component connected to your channel component. The sequence grabber component provides this value when SGInitChannel is called.
c
Identifies the connection to your channel.
p
Specifies the location of the data to be added to the movie.
len
Specifies the number of bytes of data to be added to the movie.
offset
Contains a pointer to a wide integer that receives the offset to the new data in the movie. If the movie is in memory, the returned offset reflects the location the data will have in the movie on a permanent storage device.
chRefCon
Contains the reference constant for your channel.
time
Specifies the time at which the frame was captured, expressed in the time scale associated with your channel.
writeType
Specifies the type of write operation to be used. The available values are:
seqGrabWriteAppend
Append new data to the end of the file. The sequence grabber sets the field referenced by the offset parameter to reflect the location at which data is added.
seqGrabWriteReserve
Do not write data to the output file, but reserve space in that file for the amount of data specified by the len parameter. The sequence grabber sets the field referenced by the offset parameter to the location of the reserved space.
seqGrabWriteFill
Write the data to the location specified by the field referenced by the offset parameter. The sequence grabber sets that field to the location of the byte following the last previously written byte. Use this option to fill space reserved when the writeType parameter was set to seqGrabWriteReserve.
whichOutput
Contains a pointer to the sequence grabber output to which the data was written.

DISCUSSION

SGAddExtendedMovieData differs from SGAddMovieData in two respects: the offset parameter allows a 64-bit value, and the whichOutput parameter does not exist in SGAddMovieData .

The use of whichOutput depends on the value passed in the writeType parameter. If the writeType is seqGrabWriteAppend or seqGrabWriteReserve , the whichOutput parameter is a return value specifying the sequence grabber output to which data was written or in which space was reserved. If the writeType is seqGrabWriteFill , the whichOutput parameter is an input value indicating which sequence grabber output the data should be written to.

SGAddOutputDataRefToMedia

The SGAddOutputDataRefToMedia function lets you manage capture sessions that involve multiple data references. You pass to SGAddOutputDataRefToMedia a sequence grabber output along with a media and sample description, and SGAddOutputDataRefToMedia adds the data reference to the data reference list of the specified media. SGAddOutputDataRefToMedia also updates the data reference index field of the sample description to refer to the data reference.

pascal ComponentResult SGAddOutputDataRefToMedia(SeqGrabComponent s, SGOutput sgOut,
                     Media theMedia, SampleDescriptionHandle desc);
s
Identifies a component instance that identifies the sequence grabber component connected to your channel component. The sequence grabber component provides this value when SGInitChannel is called.
sgOut
Contains a pointer to the current sequence grabber output.
theMedia
Identifies the current media. This media identifier is supplied by the Movie Toolbox.
desc
A handle containing an index assigned to the data by the toolbox call.

DISCUSSION

The SGAddOutputDataRefToMedia function is usually called from the SGAddSamples routine of the sequence grabber channel component.

SGChannelGetDataSourceName

The SGChannelGetDataSourceName function returns the data source name for a track.

pascal ComponentResult SGChannelGetDataSourceName (
                     SGChannel c,
                     Str255 name,
                     ScriptCode *scriptTag);
c
Identifies the channel connection for this operation.
name
Identifies a string that is to receive the source identification information. Set this parameter to nil if you do not want to retrieve the name.
scriptTag
Specifies a field that is to receive the source information's language code. Set this parameter to nil if you do not want this information.

DESCRIPTION

The SGChannelGetDataSourceName function allows you to get the source information specified with SGChannelSetDataSourceName .

SGChannelGetRequestedDataRate

The SGChannelGetRequestedDataRate function returns the current maximum data rate requested for a channel.

pascal ComponentResult SGChannelGetRequestedDataRate (
                     SGChannel c,
                     long *bytesPerSecond);
c
Identifies the channel connection for this operation.
bytesPerSecond
Points to a field that is to receive the maximum data rate requested by the sequence grabber component.This field is set to 0 if the sequence grabber has not set any restrictions.

DESCRIPTION

The SGChannelGetRequestedDataRate function allows the sequence grabber component to retrieve the current maximum data rate value from your channel component.

RESULT CODES

badComponentSelector

0x80008002

Function not supported

SGChannelSetDataSourceName

The SGChannelSetDataSourceName function sets the data source name for a track.

pascal ComponentResult SGChannelSetDataSourceName (
                     SGChannel c,
                     ConstStr255Param name,
                     ScriptCode scriptTag);
c
Identifies the channel connection for this operation.
name
Identifies a string that contains the source identification information.
scriptTag
Specifies the language of the source identification information.

DISCUSSION

The SGChannelSetDataSourceName function allows you to set the source information for a sequence grabber channel. You must set this information before you start digitizing.

This source information identifies the source of the video data (say, a videotape name). The sequence grabber channel stores this information in a timecode track in the movie created after the capture is complete. If the video digitizer does not provide timecode information, the sequence grabber does not save this information.

This function is currently supported only by video channels.

SGChannelSetRequestedDataRate

The SGChannelSetRequestedDataRate function specifies the maximum requested data rate for a channel.

pascal ComponentResult SGChannelSetRequestedDataRate (
                     SGChannel c,
                     long bytesPerSecond);
c
Identifies the channel connection for this operation.
bytesPerSecond
Specifies the maximum data rate requested by the sequence grabber component. The sequence grabber component sets this parameter to 0 to remove any data-rate restrictions.

DISCUSSION

The SGChannelSetRequestedDataRate function allows the sequence grabber component to specify the maximum rate at which it would like to receive data from your channel component.

The data rate supplied by the sequence grabber component represents a requested data rate. Your component may not be able to observe that rate under all conditions.

RESULT CODES

badComponentSelector

0x80008002

Function not supported

SGGetAdditionalSoundRates

The SGGetAdditionalSoundRates function returns the additional sound sample rates added to the specified sequence grabber sound channel.

pascal ComponentResult SGGetAdditionalSoundRates(SGChannel c,
                     Handle *rates);
c
Identifies the channel connection for this operation.
rates
A pointer to handle where the list of additional sample rates should be returned.

DISCUSSION

SGGetAdditionalSoundRates returns a copy of the list of additional samples rates passed to the SSGetAdditionalSoundRates previously. If no additional sample rates have been set, SGGetAdditionalSoundRates sets the rates handle to nil . The caller of this routine is responsible for disposing of the returned rates handle.

SGGetNextExtendedFrameReference

The SGGetNextExtendedFrameReference function allows a channel component to retrieve the sample references stored previously by SGAddExtendedMovieData or SGAddExtendedFrameReference .

pascal ComponentResult SGGetNextExtendedFrameReference(SeqGrabComponent s,
                     SeqGrabExtendedFrameInfoPtr frameInfo, TimeValue *frameDuration, long
                     *frameNumber);
s
Identifies a component instance that identifies the sequence grabber component connected to your channel component. The sequence grabber component provides this value when SGInitChannel is called.
frameInfo
Contains a pointer to a frame information structure defined by the SeqGrabExtendedFrameInfo data type. Your component must place the appropriate information into the record identified by this parameter. The format and content of the frame information structure are described on page 8 .
frameDuration
Contains a pointer to a time value. The sequence grabber component calculates the duration of the specified frame and returns that duration in the structure this parameter refers to. The sequence grabber component cannot calculate the duration of the last frame in a sequence. For the last frame, the time value is set to -1.
frameNumber
Contains a pointer to a long integer representing the frame number. Frame numbers may not be sequential, and may not start at 0. To retrieve information about the first frame in a movie, set the field referred to by the frameNumber parameter to -1.

DISCUSSION

SGGetNextExtendedFrameReference differs from SGGetNextFrameReference in that it fills out a SeqGrabExtendedFrameInfo structure instead of a SeqGrabFrameInfo structure.

Your channel component can process frame references sequentially or randomly. You can specify any relative frame for which you want to retrieve information.

RESULT CODES

paramErr
-50     Invalid parameter specified

SGGetPreferredPacketSize

The SGGetPreferredPacketSize function returns the preferred packet size for the sequence grabber component.

pascal ComponentResult SGGetPreferredPacketSize (
                     SGChannel c,
                     long *preferredPacketSizeInBytes);
c
Identifies the channel connection for this operation.
preferredPacketSizeInBytes
The preferred packet size in bytes.

DISCUSSION

The SGGetPreferredPacketSize function was added in QuickTime 2.5 to support video conferencing applications by making each packet an independently-decodeable chunk of data.

SGGetUserVideoCompressorList

The SGGetUserVideoCompressorList function returns the video compression formats to be displayed by the specified sequence grabber video channel.

pascal ComponentResult SGGetUserVideoCompressorList(SGChannel c,
                     Handle *compressorTypes);
c
Identifies the channel connection for this operation.
compressorTypes
A pointer to handle where the list of video compression formats should be returned.

DISCUSSION

SGGetUserVideoCompressorList returns a copy of the list of video compression formats passed to the SGSetUserVideoCompressorList previously. If no video compression formats have been set, SGGetUserVideoCompressorList sets the compressorTypes handle to nil . The caller of this routine is responsible for disposing of the returned video compression formats handle.

SGSetAdditionalSoundRates

The SGSetAdditionalSoundRates function allows an application to specify a list of sound sample rates to be included in the sequence grabber's sound settings dialog box. If any of the requested rates are not supported directly by the available sound capture hardware, sound will be captured at one of the available hardware rates and then rate converted in software to the requested rate.

pascal ComponentResult SGSetAdditionalSoundRates(SGChannel c,
                     Handle rates)
c
Identifies the channel connection for this operation.
rates
A handle containing a list of unsigned 32-bit fixed-point values. The sequence grabber channel determines the number of sample rates contained in the handle, based on the size of the handle.

DISCUSSION

The sequence grabber channel makes a copy of the additional rates handle. Therefore, your application can immediately dispose of the additional rates handle after making this call.

SGSetPreferredPacketSize

The SGSetPreferredPacketSize function sets the preferred packet size for the sequence grabber channel component.

pascal ComponentResult SGSetPreferredPacketSize (
                     SGChannel c,
                     long preferredPacketSizeInBytes);
c
Identifies the channel connection for this operation.
preferredPacketSizeInBytes
The preferred packet size in bytes.

DISCUSSION

The SGSetPreferredPacketSize function was added in QuickTime 2.5 to support video conferencing applications.

SGSetUserVideoCompressorList

The SGSetUserVideoCompressorList function allows an application to specify the list of video compression formats to be included in the sequence grabber's video settings dialog box. This allows an application to limit the number of video compression formats that will be displayed to the user. For applications using the sequence grabber for a very specific purpose, this allows inappropriate compression choices to be filtered out.

pascal ComponentResult SGSetUserVideoCompressorList(SGChannel c,
                     Handle compressorTypes);
c
Identifies the channel connection for this operation.
compressorTypes
A handle containing a list of OSTypes indicating which video compression formats should be displayed. The sequence grabber channel determines the number of video compression formats contained in the handle based on the size of the handle.

DISCUSSION

The sequence grabber channel makes a copy of the video compression formats handle. Therefore, your application can immediately dispose of the video compression formats handle after making this call.

SGWriteExtendedMovieData

The SGWriteExtendedMovieData function allows your channel component to add data to a movie.

pascal ComponentResult SGWriteExtendedMovieData(SeqGrabComponent s, SGChannel c, Ptr p,
                     long len, wide *offset, SGOutput *sgOut);
s
Identifies a component instance that identifies the sequence grabber component connected to your channel component. The sequence grabber component provides this value when SGInitChannel is called.
c
Identifies the connection to your channel.
p
Specifies the location of the data to be added to the movie.
len
Specifies the number of bytes of data to be added to the movie.
offset
Contains a pointer to a wide integer that receives the offset to the new data in the movie. If the movie is in memory, the returned offset reflects the location the data will have in the movie on a permanent storage device.
sgOut
Contains a pointer to the sequence grabber output to which the data was written.

DISCUSSION

SGWriteExtendedMovieData differs from SGWriteMovieData, in two respects: the offset parameter has a 64-bit value, and the sgOut parameter does not exist in SGWriteMovieData.

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents